Connecting to sources…

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

Documents