How to build Coglet (desktop companion robot): the whole process
133 steps to build Coglet (desktop companion robot), from buying parts, printing and assembly to software, calibration and training, with the bill of materials, shop lin…
Coglet Complete Kit from £143.57, up to £392.83 with internal prints, skin and realistic eyes (NMRobotics official store, 2026‑11‑01; the page says taxes included, and the site banner gives £10 delivery to most countries); the base kit has the CogNog board, both cameras, 9 servos, 9 TorqueStars, 65 M2 screws, power board, mic board and speaker, without printed parts. The repo gives no self-sourced BOM total
Buy parts
- Prepare asset files
Prepare the WakeNet model, text font file, and emoji image collection.
- Prepare a 5V 3A supply
Use a power supply rated for 5V and 3A, such as a USB charger with a 5V-3A rating. If using the Coglet USB > JST XH adaptor, use a USBA > USBC cable.
Assemble
- Connect the dual-MCU UART
Connect ESP32-s3 GPIO18 to RP2040 GPIO04, and ESP32-s3 GPIO17 to RP2040 GPIO05. The two MCUs exchange simple string commands corresponding to preset animations over UART.
- Connect the JST-XH power input
Connect the power through the JST-XH connector at the board’s bottom-left corner. This input powers both MCUs through 3V3 LDOs and powers the servos through an isolated 5V line.
- Follow the Feishu breadboard tutorial
Follow the linked Feishu document tutorial for the breadboard DIY practice.
Software
- Define One-Shot Action Behavior
Actions temporarily override speaking, run for 3 cycles, and then return to the previous state.
- Add the RP2040 Animation
Add the small action animation on the RP2040 side in animation.py.
- Register the Action Name
Teach RP2040/main.py the new action name so the main program recognizes it.
- Add the ESP32 MCP Tool
Add an MCP Tool on the ESP32 board file that the LLM can call.
- Send the Action Over UART
Send a simple UART string such as action:nod to trigger the action.
- Keep the Main Loop Unblocked
Avoid long sleep() calls, and never use a while True loop inside a state animation.
- Use Time-Based Animation Steps
Let main.py call the state repeatedly to move the animation forward.
- Choose Simple Action Names
Use short, lower-case action names such as excited or shy.
- Install ESP-IDF Version 5.5
Download and set up ESP-IDF version 5.5 for your operating system using the official Espressif Getting Started guide. Activate the installed environment in the terminal.
- Clone the Coglet Repository
Download the Coglet project source code using Git.
- Configure the Custom Wakeword
Open menuconfig in the ESP project, navigate to XiaoZhi Companion > Wakeword, and enter a custom wakeword. Save with S, confirm with Enter, and quit with Q; Wakeword Display controls the assistant's pronunciation.
- Build, Flash, and Monitor Firmware
Connect the Xiaozhi AI board via USB, then compile and flash the firmware. The monitor automatically opens the serial monitor so you can verify boot-up and the new wakeword.
- Open the current NMWorkbench guide
Use the linked NMWorkbench repository for up-to-date setup instructions.
- Install Ubuntu with WSL2
Open PowerShell as administrator and install Ubuntu 24.04 with WSL2.
- Create the Ubuntu user
Restart Windows if requested, open Ubuntu from the Start menu, and create a user.
- Enable mirrored WSL networking
Create C:\Users\<you>\.wslconfig with mirrored networking enabled under the wsl2 section so Coglet can reach the server.
- Restart the WSL environment
Shut down WSL in PowerShell, then reopen Ubuntu.
- Allow Coglet's firewall port
Add a Windows Firewall rule that permits inbound TCP traffic on port 18000.
- Complete the Ubuntu setup
Follow docs/GETTING_STARTED.md inside Ubuntu. Install Ollama natively on Windows for the simplest GPU option, or install it inside Ubuntu.
- Use the local Ollama endpoint
Use http://127.0.0.1:11434/v1 as the Ollama endpoint with mirrored networking, whether Ollama is installed on Windows or inside Ubuntu.
- Set Ollama's context length
Set the Ollama context length to 16384 using OLLAMA_CONTEXT_LENGTH. Set it as a Windows environment variable for the Windows app, or follow the guide for the Ubuntu installation.
- Keep the board identifier unique
When the custom IO configuration differs from the original board, do not overwrite and compile the original board configuration; create a new board type or use a different name and sdkconfig macro definition in config.json builds.
- Learn the board directory files
A board directory usually contains xxx_board.cc, config.h, config.json, and README.md for board initialization code, hardware configuration, build configuration, and board documentation.
- Create the custom board directory
Create a new directory under boards/ and use the brand-name-board-type naming form; the example name is m5stack-tab5.
- Define the hardware pin configuration
- Create the board build configuration
In config.json, set target to esp32s3 and add a build named my-custom-board under builds; sdkconfig_append adds the 8MB Flash setting and the partitions/v2/8m.csv partition table. The target must match the hardware, the name is recommended to match the directory name, and sdkconfig_append is added to the default configuration.
- Select Flash and partition settings
Select CONFIG_ESPTOOLPY_FLASHSIZE_4MB=y, CONFIG_ESPTOOLPY_FLASHSIZE_8MB=y, or CONFIG_ESPTOOLPY_FLASHSIZE_16MB=y in sdkconfig_append according to the hardware, and optionally select the partitions/v2/4m.csv or partitions/v2/8m.csv partition table.
- Compile and package the board firmware
After completing the custom board configuration, run scripts/release.py with the board directory name to compile and package the firmware for that board.
- Create the custom board file
Create `my_custom_board.cc` and implement all board initialization logic in it.
- Define the custom board class
Define the board class in `my_custom_board.cc`, inheriting from `WifiBoard` or `Ml307Board`.
- Implement component initialization
Implement initialization functions for I2C, SPI, display, buttons, IoT, and other components. The shown display initialization uses ST7789 and initializes the panel interface through SPI2_HOST.
- Override board virtual functions
Override virtual functions such as `GetAudioCodec()`, `GetDisplay()`, and `GetBacklight()` in the board class.
- Register the custom board
Register the custom board using the `DECLARE_BOARD` macro.
- Add custom board option
Add `BOARD_TYPE_MY_CUSTOM_BOARD` under `choice BOARD_TYPE` in `main/Kconfig.projbuild`, and set `depends on` for the target chip.
- Add CMake board configuration
Add the custom board configuration to the `elseif` chain in `main/CMakeLists.txt`, setting `BOARD_TYPE` to `my-custom-board` to match the directory name.
- Select fonts by screen size
Use `font_puhui_basic_14_1` and `font_awesome_14_1` for a 128x64 OLED, 16_4 fonts for 240x240, 20_4 fonts for 240x320, and 30_4 fonts for 480x320 and larger.
- Choose emoji collection
`twemoji_32` provides 32x32 pixel emojis for small screens, while `twemoji_64` provides 64x64 pixel emojis for large screens.
- Set ESP32 target chip
On the first configuration or when changing chips, run `idf.py set-target` with ESP32-S3, ESP32-C3, or ESP32 according to the board.
- Clean old configuration
Run `idf.py fullclean` to clean the old configuration.
- Select the custom board
Run `idf.py menuconfig`, navigate to `Xiaozhi Assistant` -> `Board Type`, and select the custom board.
Calibrate and test
- Check the Incoming UART Name
If nothing happens, check the exact string name arriving over UART.
- Check the Servo Abbreviation
If the wrong part moves, check the servo abbreviation, such as EAL or EAR.
- Restore a Safe Servo Angle
If movement is too large, return to a known-safe angle from an existing animation.
- Use the Priority Action Path
Ensure the MCP Action uses the higher-priority action path so it does not conflict with Speaking.
- Check the console OTA URL
Open the Overview page in the console and verify that the OTA URL shows the PC's LAN IP, such as 192.168.x.x.
- Configure Coglet's OTA URL
Enter the Overview page's OTA URL in Coglet.
- Output an Acoustic Test Signal
Output the acoustic `demod` through `sonic_wifi_config.html`, or upload it to PinMe’s Xiaozhi acoustic configuration at https://iqf7jnhi.pinit.eth.limo for output.
- Adjust Noise Reduction per Board
Some ADCs require finer noise-reduction adjustments during the I2C configuration stage; because the devices are not universal, testing currently uses the configs provided in boards.
- Configure lichuang-dev Reception
The lichuang-dev uses an ES7210 ADC and requires `INPUT_REFERENCE` to be disabled during testing.
- Configure kevin-box-2 Reception
The kevin-box-2 uses an ES7210 ADC and requires `INPUT_REFERENCE` to be disabled during testing.
- Configure m5stack-core-s3 Reception
The m5stack-core-s3 uses an ES7210 ADC and requires `INPUT_REFERENCE` to be disabled during testing.
- Flash the built firmware
Flash the built firmware to Coglet. After flashing, Coglet can be asked to dance to a named song or to one of the user's songs.
- Override preset and tempo in filenames
Coglet selects the preset automatically, or filename tags can force the preset and tempo when detection is off. Examples are "Night Rain.calm.mp3", "Drop It.energetic.wav", and "Free Fall.calm.68bpm.m4a".
- Check build outputs
Confirm that build/assets/ contains all asset files, build/output/ contains intermediate outputs, and build/ contains assets.bin, config.json, and assets/.
- Check asset file size
Ensure the generated `assets.bin` file does not exceed the SPIFFS partition size.
Data and training
- Convert regular audio to P3
Run convert_audio_to_p3.py with the input audio file and output P3 file; the default loudness-normalization target is -16 LUFS.
- Disable loudness normalization when needed
Use `-d` when the audio is too short, has already been loudness-adjusted, or comes from the default TTS, whose loudness is already -16 LUFS.
- Convert P3 back to regular audio
Run convert_p3_to_audio.py with the input P3 file and output audio file; the output audio file must have an extension.
- Run the batch conversion GUI
Run batch_convert_gui.py to open the graphical batch converter supporting audio-to-P3 and P3-to-audio conversion.
- Save and Analyze Received Audio
Save audio for the window length to assess noise-frequency distribution and the accuracy of acoustic ASCII transmission.
- Test atk-dnesp32s3-box0 Decoding
The atk-dnesp32s3-box0 uses an ES8311 ADC and can receive and decode audio, but its packet-loss rate is very high.
- Test movecall-moji-esp32s3 Decoding
The movecall-moji-esp32s3 uses an ES8311 ADC and can receive and decode audio, but its packet-loss rate is very high.
- Send Opus Audio Over the Network
Have the application layer retrieve the Opus packets from `audio_send_queue_` and send them over the network to the cloud server.
Use it
- Ask Coglet to dance
Say "dance to <song name>" for a particular song. Say "dance to one of my songs" to request one of the songs added by the user.
- Use the energetic preset
The whole robot dances with head bobs, ear movement, swaying, base turns, eye movement, and blinks.
- Use the calm preset
Only the ears, head, and base move gently with the felt pulse. The eyelid and eye servos are relaxed and have no torque during the song.
- Play a P3 audio file
Run play_p3.py with the P3 file path to decode and play it, applying a fade-out when playback ends or the user interrupts it.
Common problems
- Provided 3MF files are invalid and cannot be parsed #5 #8
- Some parts are too thin or repeatedly fail during printing #4 #10
- Random seam settings cause zits on printed surfaces #12
- RP2040 MicroPython code is not provided or clearly located #1
- Iris component is absent from printed parts and its fabrication is unclear #6
- Project lacks a license file, restricting legal use #3
- Computer does not recognize RP2040 or ESP32 after PCB assembly #7
Parts
- CogNog board: ESP32‑S3 (Wi‑Fi/BLE, AI acceleration) plus RP2040 (real-time servo animation), PCA9685 16-channel PWM, MAX98357A amplifier, CH343P USB-UART; 72×81 mm, four layers, up to 12 servos
- 9 metal-gear micro servos: two ears, eyelid, mouth, two eyes, neck pitch and roll, base yaw (the datasheet links the TiankongRC TS90MD; the README says MG90S may also work) plus 9 TorqueStar spline adapters (printable in resin)
- GC0308 camera (custom reversed pinout), Grove Vision AI V2 with an OV5647 HD camera and 15-pin flex cable
- I2S microphone board (6-pin reversed PicoBlade cable), 4 Ω 3 W speaker
- 5V 3A USB power through a USB-to-JST‑XH power board (a USB‑A to USB‑C cable is required); powering from the programming port leaves the servos unpowered
- FDM-printed internal parts and skin (Bambu Lab 3MF, 0.4 mm nozzle), with optional SLA resin skins and realistic eyeballs
Tools
- An FDM 3D printer with a 0.4 mm nozzle, or printed parts from the store
- A 5V 3A USB charger and a USB‑A to USB‑C cable
- For development: ESP‑IDF 5.5, MicroPython with Thonny (RP2040), and SenseCraft to deploy the face detection model
Skills
- 3D printing and fitting servos into tight spaces, using the on-board calibration switch to centre them
- Wi‑Fi setup and the XiaoZhi AI dashboard
- Advanced: ESP‑IDF C++ (XiaoZhi framework and MCP tools) and RP2040 MicroPython animation (animation.py)
Software
- CogletESP: ESP32‑S3 firmware built on XiaoZhi AI, with streaming speech recognition, LLM and speech synthesis, MCP device control and a configurable wake word
- RP2040 MicroPython animation code: expression states (happy, sad, listening, speaking) and one-shot actions (head shake, blink)
- Local face detection on the Grove Vision AI V2 (SenseCraft model); on-board servo test button and face-tracking switch