How to build Spot Micro - Leika: the whole process
133 steps to build Spot Micro - Leika, from buying parts, printing and assembly to software, calibration and training, with the bill of materials, shop links and the off…
Spot Micro - Leika is an ESP32-based quadruped robot platform. The repository provides printable parts, a component and BOM guide, assembly and setup instructions, embedded firmware, a web controller, and a MuJoCo simulator.
Buy parts
- Build firmware from source
No firmware has been published yet; build it from source using the software guide.
Print and make
- Use the stand top STL
Use `2x_stand_top.stl` for the stand top. The file comes from stefi01’s “stronger microspot stand top”.
- Use the stand bottom STL
Use `2x_stand_bottom.stl` for the stand bottom. The file is derived from Nova-SM2.
- Use the stand brace STL
Use `2x_stand_brace.stl` for the stand brace. The file is derived from Nova-SM2.
- Use the stand feet STL
Use `4x_stand_feet.stl` for four stand feet. The file is derived from Nova-SM2.
Software
- Configure the ESP-IDF firmware build
Use PlatformIO with framework set to espidf in platformio.ini. The firmware targets ESP32, ESP32-S3 and ESP32-P4.
- Use the repository drivers
The sensor drivers, IMU fusion, PCA9685 driver and I2C bus layer are in esp32/include/peripherals and are part of the repository, not external libraries.
- Install external software dependencies
Install espressif/mdns, joltwallet/littlefs, espressif/esp-dsp, espressif/led_strip and espressif/esp32-camera from the ESP-IDF component manager on every target except ESP32-P4. ESP32-P4 uses esp_wifi_remote, esp_hosted and esp_cam_sensor.
- Run the control task
Use SpotControlLoopEntry in esp32/src/main.cpp to execute the control loop every 10 ms.
- Select and connect the IMU chip
The firmware probes for the first chip that answers, in the order ICM-20948, BNO055, MPU6050. The ICM-20948 and the MPU6050 share address 0x68, and starting an MPU6050 resets whatever chip is there.
- Enable or disable sensors in peripheral settings
A sensor disabled in the peripheral settings is only identified by its address and chip ID, so the app can show it as detected and it is never configured. Changing what is disabled probes again and restarts the fusion.
- Select geometry and joint model
The variant uses `variant.h` to select leg geometry `KIN_CONFIG_*` from `kinematics.h` and the joint model from `joint_model.h`.
- Configure twelve-joint servo output
Drive the twelve joints with a PCA9685 at 50 Hz using a 27 MHz oscillator.
- Separate speed limiting and smoothing
Speed limiting is the only filtering between motion-state angles and the servos; the motion states perform command smoothing.
- Connect to the Robot API
Use the /api/ws WebSocket with protobuf messages from platform_shared/message.proto. Commands, periodic broadcasts, settings, file transfer, and per-tick telemetry travel through it, while the camera stream separately uses /api/camera/stream.
- Use the Serial Links
Carry the protocol and log over the serial link on the USB-Serial-JTAG port, with requests accepted only on the console UART. The SerialLink adapter handles each port as one client and sends the log through its writer.
- Subscribe to States and Streams
Subscribe to the required streams on the connection; the firmware registers handlers on every link and sends each stream to its subscribers. A state subscription returns the current value first and then pushes every change, while an unaccepted push is sent again as the current value on the service task’s next pass.
- Connect the Bluetooth App Link
On S3 boards with PSRAM, the NimbleLink adapter serves the app over a Bluetooth LE Nordic UART Service. It provides the WebSocket commands, requests, and broadcasts, but no telemetry or file or firmware transfer.
- Check ESP32-P4 Support
The ESP32-P4 has no radio of its own for ESP-NOW, so builds omit the receiver. The features report espnow_controller_supported as unsupported.
- Configure Firmware Build Options
Build one firmware per PlatformIO environment for every variant and sensor combination, and always embed the web app. Keep board-fixed settings as defines in the environment's `build_flags`.
- Build the embedded controller
Run `pnpm build:embedded`. The result is embedded in the firmware image as compressed assets and omits the 3D view and simulation to save flash.
- Build the hosted controller
Run `pnpm build` to build the hosted version. This version includes both the 3D view and the simulation.
- Start the Vite development server
Run the application in Vite development mode with `pnpm dev`.
- Build the GitHub Pages static site
Use `pnpm build` to produce the static site hosted by GitHub Pages; `BASE_PATH` sets its sub-path.
- Build the firmware-embedded version
Use `pnpm build:embedded` to produce the version embedded in the firmware flash, without the 3D view and simulation.
- Install development prerequisites
Prepare Node.js 20.19+ or 22.12+, pnpm, and `protoc` on `PATH`. The `.npmrc` file sets `engine-strict`.
- Install project dependencies
Run `pnpm install` in the app directory.
- Generate shared protocol code
Run `pnpm proto` to generate `src/lib/platform_shared` from `../platform_shared`; Git ignores the generated directory.
- Run the development app
Run `pnpm dev`; it runs `pnpm model` first, then starts Vite on port 5173.
- Copy simulation models
Run `pnpm model` to copy simulation models from `../simulation/src/resources` into `static/`.
- Build and preview the static result
`pnpm build` runs `proto` and `model` itself. Run `pnpm preview` to serve the result on port 4173.
- Run lint checks
Run `pnpm lint` to perform the Prettier check and ESLint.
- Run Svelte checks
Run `pnpm check` to execute `svelte-kit sync` and `svelte-check`.
- Run unit tests
Run `pnpm test` to execute Vitest against `tests/unit` once.
- Format project files
Run `pnpm format` to write formatted files with Prettier.
- Run unit tests in watch mode
Run `pnpm test:unit` to run Vitest in watch mode.
- Test Show on robot
With Show on robot on, drag a pose in the editor and then close the app mid-pose. The robot should follow the drag and ease back to stance once the app is gone.
- Upload and play an animation clip
Upload the clip with `robot_animate.py --robot <ip> upload <clip.json>`, then play it over USB.
- Download and restart the robot
Download a release with `<env>.bin` from GitHub Pages, follow the redirect, and restart into it. The download should complete, boot from the other slot, confirm the image, and report the release's ELF hash.
- Crash intentionally and decode the dump
Crash the robot on purpose, then download the dump from the status page and decode it as in `docs/websocket.md`, Decoding a dump. The Last crash card should name the task and reason, state that the dump is from the running build, and the decoded result should show the crashing task's backtrace.
- Connect the board over USB
Connect the board over USB with a data cable; some boards require holding BOOT while plugging in.
- Check flash capacity
The board must have at least 4 MB of flash.
- Know the first-install erase
A first install erases the board, including saved settings.
- Close the installer dialog
Close the installer dialog, which holds the port until then.
- Synchronize the Python environment
Use uv with Python ≥ 3.13 and run uv sync to synchronize the environment.
Calibrate and test
- Copy the latest IMU sample
The control task copies the latest IMU sample.
- Update the motion service
Run MotionService::update to apply the inbox, step the active motion state, solve the inverse kinematics and apply the per-joint sign.
- Switch the servo board state
When the mode changes, activate or deactivate the servo board.
- Update the servo controller
Run ServoController::update to limit each joint's speed, convert the angles to PWM and write all PCA9685 channels in one I2C burst.
- Wait for the next control tick
The control task waits for the next tick. If a tick overruns, it restarts the schedule instead of catching up.
- Probe sensors at boot
Every driver is built in, and the sensor task probes the I2C bus at boot.
- Set the mounting matrix
Enter the mounting matrix in the peripheral settings; it rotates the chip frame into the body frame (x forward, y left, z up).
- Measure gyro bias at boot while still
At boot, keep the robot still while the bias is measured over 200 samples. If the robot moves, the bias is left at zero.
- Set the Madgwick filter gain
For the MPU6050 and the ICM-20948 a Madgwick filter fuses the gyro and the accelerometer, and the compass when a fresh reading exists. Its gain is an IMU setting that defaults to 0.1, and is 2.5 during the first two seconds.
- Fold the still tilt into the stored mounting
Fold the tilt of a still robot into the stored mounting from the app so a robot on a level surface reads level. The tilt must be under 15 degrees.
- Set up the separate HMC5883L compass
A separate HMC5883L compass (75 Hz) supplies the compass for a chip without one. Its alignment, hard-iron offset and soft-iron matrix are IMU settings.
- Handle a silent compass
A compass that has been silent for three of its periods is ignored. A disabled compass is left out of the fusion, the chip's own as well as a separate one.
- Set the INA219 address and A0
The INA219 sits in the servo rail. 0x40 is the PCA9685's address, so the INA219's A0 is tied high and its address is a peripheral setting.
- Calibrate INA219 shunt and max current
Its calibration follows from the shunt resistance and the largest current expected, both settings (0.1 Ohm and 3.2 A by default). The current's resolution is that current over 2^15, and the shunt range the narrowest of 40 - 320 mV that holds it.
- Set voltage and current averaging windows
The bus voltage is averaged over 8.5 ms so that a dip shows, the shunt over 68 ms so that the current is the mean between reads.
- Set the under-voltage cut-off
Below the cut-off voltage (a setting, 0 for off by default) for 2 s, the robot deactivates and logs why, and it is held deactivated until the rail rises 0.2 V above the cut-off; the servos going limp take their load off.
- Detect stall current
Set a stall flag when current stays above the default 3 A stall current for the default 1 second stall time; the flag is only reported.
- Read the robot variant
The variant is a robot setting in `robotSettings.pb`, read by `app_main` before any task starts.
- Apply a deactivated variant change
Accept a variant change only while the robot is deactivated. Store and post it to the control task, which switches the motion code and joint model in one tick and resets the body to the new variant's default pose.
- Handle a robot without a variant
A robot without a variant has neither leg geometry nor a joint model; the motion service rejects every mode except deactivated, and the servo board remains asleep.
- Keep the servo board initially asleep
Start the board asleep with every channel off so the legs do not jump to a pose retained by the board across a reset.
- Set joint model parameters
The variant's `joint_model.h` provides each joint's sign, the servo angle at its kinematic zero, and 2.0 PWM counts per degree.
- Read joint calibration and channels
The robot calibration in `servoSettings.pb` contains each joint's centre PWM, 306 by default, and optionally its PCA9685 channel.
- Clamp the servo PWM range
Clamp each joint's PWM to 125–600 counts, the accepted servo range.
- Calculate speed from supply voltage
The rated speed is 720 degrees per second at 6 V and 443 at 4.8 V, interpolated linearly between them and held at the nearer value outside that range.
- Limit the tick duration
Count a tick as at most 20 ms so that a stall does not release a jump.
- Synchronize speed limit with walking
A new supply applies from the next tick. The control task passes the same limit to walk, whose joints are capped at three quarters of it.
- Configure LittleFS Settings
Store WiFi, access point, camera, servo, peripheral, and robot settings as protobuf files in the /config directory of the LittleFS partition. Peripheral settings include pins, I2C frequency, IMU, disabled sensors, and the LED strip.
- Enable the ESP-NOW Receiver
Switch on the receiver in the peripheral settings on the Sensors page. The receiver is off by default because it beacons ten times a second.
- Prepare Pico and acceptance log
Wait for the powered Pico and run the Python tools from `simulation/` with `uv run python`. Write every outcome, including failures, into a new section above, headed with the date, branch and firmware ELF hash from the status page in the table format.
- Test Bluetooth and WiFi buffers
With Bluetooth on, read the boot log's `Bluetooth took N bytes` line and time a file download over WiFi. Record the bytes and the download time against a build without Bluetooth.
- Check RAM after camera initialization
On a camera board with the camera env, read the status page's internal RAM, largest block and low mark after the camera has started. The Pico has no camera, so use another board.
- Verify stick direction conventions
On the floor at a small stick, verify that in STAND the left stick right leans the body right; in WALK `+lx` strafes right and the right stick left (`+rx`) turns anticlockwise seen from above. Record whether every check matches.
- Verify odometry and goal motion
Run `odometry_request`; `yaw` and `kinematic_yaw` should have the same sign, positive for an anticlockwise turn. Run `goal_move(sideways=0.1)` to go left and `goal_move(turn_deg=90)` to turn anticlockwise and stop; record the outcomes.
- Confirm the calibration front-left leg
On the calibration page, confirm that the leg labeled "Front left" is the leg that moves. Record whether the check matches.
- Verify the four-bar knee
On the calibration page, set one knee to its centre PWM + 40. The real tibia should turn about 1.7 times the turn shown in the 2D diagram; record the outcome.
- Verify the joint limits
In IDLE, drive each joint to its limit from the 3D model. The full-size knee should stop at 149 degrees, the Pico knee at 153 and the Pico coxa at -77 without touching the frame; the limits are estimates.
- Stand from rest or walking
Press STAND from REST and from a walk. Expect the feet to ease in over 0.5 s with no snap and no foot dragged.
- Test servo switch and PWM
On the servo page, switch the servos off, then on, then set one servo's PWM. Off should leave every servo limp; on should drive nothing until PWM is set, after which only that servo moves, for 757a64eb.
- Measure and set servo supply
Measure the servo rail and enter it on the servo page, using the INA219 at 0x41 where fitted, then set the low-battery cut-off. The status page should show the rail voltage and current, and the walk speed cap should follow the entered supply without a restart.
Data and training
- Record telemetry data
The control task records a telemetry tick only while a client is subscribed to the telemetry stream.
- Record supply telemetry
Readings stream as `PowerData`. Each telemetry network sample contains the rail voltage, its lowest voltage since the previous sample, and current, so recordings show supply dips.
- Collect Robot Telemetry
Have a client subscribe to telemetry to receive IMU, sonar, servo rail, and RSSI broadcasts every 100 ms and system analytics every 2 s. The control task places one sample per tick in a 64-tick ring, and the service task sends batches of 10 preceded by a header describing the firmware, variant, IMU, and settings.
- Record the Telemetry Stream
Keep the client subscribed to record the telemetry stream; recording stops when it is no longer subscribed. The recorded stream contains the telemetry batches sent by the service task.
- Record rise roll and pitch
Record for 10 seconds with record.py while pressing STAND from REST, then run report_recording.py on the file. Compare roll and pitch over the first 2 s against the pre-compensation roll of -13 degrees and pitch of +8 degrees.
- Test goal moves
Against a tape measure, run `goal_move(forward=0.2)` and `goal_move(turn_deg=90)` from the Python client, then test a goal whose client is closed mid-goal and one with a stick nudged mid-goal. The distance and turn should be within the odometry's error; the closed client's goal should cancel and the nudged goal should be handed to the stick.
- Record for system identification
Make a recording that starts with the robot standing still, then run `identify.py` on it.
- Train the PPO residual gait policy
The PPO policy learns small per-foot corrections over the baseline gait, keeping training focused on stabilization.
- Export and deploy the trained policy
Export the trained policy to the firmware and run it as the `WALK_NN` mode. See the simulation README's deployment section for details.
- Record telemetry and compare simulation assumptions
Use `record.py` to capture the real robot's telemetry, then use `report_recording.py` to compare it with the simulation's assumptions.
- Run the training pipeline smoke test
Run a quick sanity check of the training pipeline.
- Train the randomized policy
Train with randomization, zero final state, initial standard deviation 0.3, curriculum, 300 resampled steps, 5,000,000 timesteps, and 16 environments.
- Record real robot telemetry
Record 60 seconds of telemetry from the robot at 192.168.1.39; use --out to set the output file.
- Analyze a robot recording
Report the timing and IMU noise of recording.leika compared with domain_rand.py; use --still for a still.
- Train on uneven ground
Train on the heightfield scene with --terrain 0.008; per-episode random bumps are up to 0.008 metres.
Use it
- Test AUTO walking speed at swap
On the floor, walk just below and just above one fifth of the stick with a standstill between, using a tape measure. The commanded speed should not jump at the swap; the Pico's reach limit leaves the crawl at about 0.82 of full stroke, while walked speed rises about 1.2 times there.
- Raise step height mid-walk
While walking forward, move the step height slider from 0.25 to 1. Expect the raised feet to rise over about one third of a second instead of jumping.
- Test sticks over Bluetooth
Drive from the app over Bluetooth with the robot on the stand and then on the floor. Expect the robot to follow the sticks as over WiFi and to stop on release.
- Test camera stream while driving
With a camera board, open the stream and drive. Expect the stream to keep up and the WebSocket to keep answering; the Pico has no camera.
- Run floor benchmark
Lay out the course from `docs/benchmark.md` and run it.
- Test built-in animation clips
The clips passed on the stand on 2026-10-28; play them standing on the floor. The wave keeps 26 mm of centre-of-mass margin in the simulation and had tipped the robot at 9 mm on 2026-10-28; it should not tip or rock the robot.
- Confirm sensors are optional
All sensors are optional. The robot walks without any of them, but stand mode levels the body only with an IMU.
- Use the pose ladder gestures
In `esp32/include/gesture_control.h`, moving down steps from walk to stand, from stand to the held built-in `sit` clip, and then to rest; moving up returns to stand, while left and right select walk.
- Run walking and turning goals
From stand or walk, forward and backward walk 10 cm, while anticlockwise and clockwise each turn a full circle; the odometry performs them as goal moves.
- Discard conflicting gestures
A gesture arriving while a leg clip is moving or a goal is running is discarded rather than queued.
- Wake servos by mode
Wake the board when rest, stand, or walk is selected, or when the app activates the servos. Selecting deactivated, idle, or calibration puts it back to sleep.
- Drive with the Handheld Controller
Drive the robot without the app using the separate esp-now-controller firmware. ESP-NOW has no pairing, so the robot obeys the first controller whose frame it hears after startup and ignores other senders; switching the receiver off and on lets another controller take over immediately.
- Switch between simulation and physical robot
`Robot("simulation")` and `Robot("<robot address>")` expose the same calls; changing the target lets a simulation script run on the robot.
- Watch the baseline gait
Watch the baseline gait in the viewer with vx 0.05.
- Evaluate a trained policy
Watch the trained policy run; use --headless to print tracking metrics.
- Run the Robot API demo
Run the Robot API demo; providing an address drives the real robot.
- Inspect the policy in TensorBoard
Start TensorBoard with the runs log directory; terms/r_vel tracking should rise while terms/p_res residual magnitude stays small.
Common problems
- Setup fails from missing manifests, wrong paths, or incomplete instructions #42 #73 #176 #178
- PlatformIO firmware fails to build or upload successfully #1 #36
- Pin mappings and wiring schematics are insufficiently documented #2 #45
- Servo calibration and gait behavior are unclear in firmware #175
- I2C sensors fail to communicate after hardware connection #51 #58
- Camera uploads successfully but live streaming fails #37
- Web controller requests return invalid-method HTTP errors #180
- ESP32 firmware exhausts memory during initialization #179