Connecting to sources…

How to build Blossom (handcrafted open-source social robot): the whole process

158 steps to build Blossom (handcrafted open-source social robot), from buying parts, printing and assembly to software, calibration and training, with the bill of mater…

Not sold. The rebuild docs put the Dynamixel configuration under $200 in components and the micro-servo plus Arduino configuration at about $50 (GitHub blsm.md, 2026‑10‑31); the original BOM lists parts without prices

Bill of materials · Parts

PartQtyANY
blsm_A · Part runner · Print1
blsm_B · Part runner · Print2
blsm_C · Part runner · Print2
blsm_D · Part runner · Print1
blsm_E · Part runner · Print3
blsm_F · Part runner · Print3
blsm_M · Part runner · Print4
blsm_SR · *S*lip *R*ing for rotating the upper body · Print the static non-rotating 'dummy' model, or use the actual 12-wire slip ring to enable continuous rota1USD 22
String · String for actuating the head · Purchase (e.g. fishing line, twine)1USD 5
Rubber bands, 4mm diameter · Rubber bands for hanging the head platform · Purchase e.g. black rubber bands6USD 8

Bill of materials · Motors and electronics

PartQtyANY
Arduino (or clone) · Microcontroller and cable · Purchase1USD 15
Micro servo · Small servos with basic position control · Purchase4USD 10
Dynamixel U2D2 · Motor controller · Purchase1USD 32

Buy parts

  • Choose the Standard Dynamixel Configuration

    Choose Dynamixel smart servos for the full-featured version; they provide position- or velocity-control modes, velocity and acceleration profiles, and PID tweaking.

  • Choose the Low-Cost Arduino Configuration

    Use an Arduino and micro servos for approximately $50, equivalent to one Dynamixel; movement is noisier and less smooth, and left-right yaw rotation is limited to ±90°.

  • Obtain USB Power Breakouts and Cables

    Both configurations require USB breakouts for power and some cables.

  • Buy the Minimal M2 Hardware Set

    All of the minimal hardware required for M2 is available in the linked set for $10.

  • Open the Blossom Build Guide

    Follow the Build Guide to make your own Blossom; the document also states that the basic software setup above is needed before running the robot.

Print and make

  • Download Blossom STL Files

    Download a complete runner STL such as blsm_A or an individual part STL such as A1 from the listed directories.

  • Print the Blossom Parts

    Print the downloaded parts on an entry-level Creality Ender 3.

  • Slice Files with Cura Profile

    Open the STL files in Cura and slice them with the provided blsm-020.curaprofile profile.

  • Print or laser-cut the modular parts

    Fabricate the redesign as smaller parts, printed individually or in model-kit-style “runners”; adjust tolerances when laser-cutting from wood.

Assemble

  • Assemble the Robot from Instructions

    Assemble the printed robot by following the linked Blossom PDF instructions.

  • Connect the U2D2 and External Power

    Set up the Dynamixel configuration by connecting the U2D2 controller to an external power supply according to the wiring documentation.

  • Arrange Motors in the Specified Order

    From top to bottom, motor 4 is the base motor, motor 3 is the robot’s left motor, motor 2 is the right motor, and motor 1 is the front motor.

  • Connect the Pico and Zero UART Pins

    After unplugging USB, connect the Pico UART pins to the Pi Zero.

  • Connect the Motors to the Pico

    Connect the motors to the Pico.

  • Connect the 5V Power

    Connect the motors to 5V power.

  • Insert the microSD Card

    Insert the microSD card into the Pi Zero.

  • Disconnect the Pico

    Disconnect the Pico from the computer.

  • Connect Pico to Zero

    Following the wiring diagram, connect the Pico's power and UART pins to the Zero.

  • Connect Servos and GPIO

    Following the wiring diagram, connect the servos to the Pico's GPIO pins and a separate power supply.

  • Power the servos from 5V USB

    The XL-330 nominally operates at 5V, which can conveniently be tapped from any USB power supply.

Software

  • Clone the r0b0 Repository and Submodules

    Clone the r0b0 repository, including its submodules, on the computer.

  • Connect USB to the Pico

    Plug the Pico into the computer with USB.

  • Load Firmware onto the Pico

    Load the firmware onto the board.

  • Build and Load the C++ Firmware

    Build the C++ firmware on the computer and load it onto the board.

  • Copy the Firmware Files

    Copy the required files from the computer to the Pico, then unplug USB.

  • Download Raspberry Pi Imager

    Download the Raspberry Pi Imager, called “Raspbery Pi Imager” in the document, on the computer.

  • Back Up the Project Image

    Back up the project image.

  • Write the Image to the microSD Card

    Use Raspberry Pi Imager to burn the image onto a microSD card.

  • Connect Zero’s Data USB Port

    Plug USB into the Pi Zero; use the Zero’s USB data port, not the PWR port.

  • Clone the Repository on Zero

    Clone the project repository on the Pi Zero.

  • Install Docker

    Install Docker on the Pi Zero.

  • Enable Serial Communications

    Enable serial communications on the Pi Zero.

  • Build the Container

    Build the project container on the Pi Zero.

  • Configure the Boot Service

    Configure the service to run automatically on boot.

  • Reboot the Pi Zero

    Reboot the Pi Zero.

  • Clone the Firmware Repository

    Clone the micropython-servo repository on your local computer, not on the Zero. Switch to the msgtn/251210 branch and enter the cpp directory.

  • Connect the Pico

    Connect the Pico to your computer through its USB port, then follow the listed instructions to install the Pico SDK, build the firmware, and load it.

  • Install the Pico SDK

    Clone the raspberrypi/pico-sdk repository and initialize its submodules. Set PICO_SDK_PATH to the actual pico-sdk path on your machine.

  • Install Build Dependencies

    Install cmake, gcc-arm-none-eabi, libnewlib-arm-none-eabi, and picotool.

  • Configure and Build Firmware

    Enter the cpp directory, create a build directory, and run the CMake configuration and build. The default build configuration is for PWM servos.

  • Complete Firmware Build

    Enter the build directory and run make with four parallel jobs.

  • Load Firmware onto Pico

    Force the Pico into BOOTSEL mode, then load servo_controller.uf2.

  • Reboot into Application Mode

    After loading the firmware, reboot the Pico into application mode.

  • Download Raspberry Pi Imager

    Download the Raspberry Pi Imager.

  • Connect the microSD Card

    Connect a microSD card to the computer.

  • Flash the Image onto the SD Card

    Open Raspberry Pi Imager and flash the image onto the SD card.

  • Select the Zero 2W Image

    Select the Bookworm 64-bit image for Pi Zero 2W. The option may be hidden in an “other” or “legacy” section.

  • Configure the Local Network

    Configure the Zero to connect to your local network.

  • Set the Zero Username

    Set the Zero's username to blsm. The startup services require this username.

  • Enable SSH

    Enable ssh in Raspberry Pi Imager.

  • Connect to the Zero

    Use SSH to log into the Zero at its IP address with the blsm account.

  • Install Dependencies and Test Docker

    Enter the top-level r0b0 directory, install dependencies including the WiFi access point configurator, and run hello-world to test Docker.

  • Build the Blossom Container

    Build the Blossom container from the top-level r0b0 directory.

  • Configure the WiFi Access Point

    Start the WiFi access point configurator and save the output SSID and password.

  • Enable the Serial Device

    Edit /boot/firmware/config.txt, add enable_uart=1 at the end, then press Ctrl-X and Y to save and exit.

  • Set Up the Startup Service

    Run the service script so the blsm container runs on boot.

  • Reboot the Zero

    Reboot the Zero so the /dev/serial0 enablement takes effect.

  • Install Expo Client

    Install the Blossom App on Android or iOS through the Expo Client app.

  • Install a build tool

    To build the app yourself, your computer must have either npm or yarn installed.

  • Install watchman on OSX

    On OSX, install watchman with brew.

Calibrate and test

  • Configure the Zero Access Point

    Configure the access point on the Pi Zero.

  • Command Motors to the Calibration Position

    Command the motors to move to the calibration position through the control interface.

  • Reattach Servos in Configuration Orientation

    Reattach the servos in the orientation required by the calibration configuration.

  • Remove the wheels

    Remove the wheels first if they are already attached to the servos.

  • Open the calibration interface

    Click `Calibration` on the interface, or go to `https://{ip-address}:8080/blsm_calib`.

  • Reset to calibration position

    Click `Reset to Calibration Position` to move all motors to the calibration position.

  • Reattach the wheels

    Reattach the wheels with the strings pointed down, or align the servo horn with the body of the servo.

  • Set the XL330 motor goal position

    Set motor 2's goal position to 1000; use 1000 for the towers and 2000 for the base.

  • Set the XL320 motor goal position

    Set motor 2's goal position to 700; use 700 for the towers and 500 for the base.

  • Stop the position-setting script

    Press Ctrl+D to stop the script.

  • Calibrate the remaining motors

    Repeat the goal-position setup for motor IDs 3 and 4.

  • Fix port permission errors

    If opening the port produces an error, change the permissions of /dev/ttyACM0 to 777. Alternatively, rerun everything with admin privileges.

  • Set Serial Port Permissions

    If the “could not open port” error appears, run the example permission command on the port.

  • Specify the Actual Linux IP Address

    If Linux defaults to the loopback IP `127.0.1.1`, you must specify the IP address with `-i`.

  • Read the Startup IP Address

    Read the IP address and port shown in the startup prompt; the example is `10.132.3.171:8000`, but the actual address will differ.

  • Connect and enable robot control

    Enter the IP address in the `Host` field, then toggle `Control robot` on.

  • Update the editor IP address

    Enter the IP address in the editor and press `Update IP Address`.

  • Adjust motion and posture

    Adjust the playback speed, exaggeration (amplitude), and posture, including leaning forwards or backwards.

  • Set the adjustment multiplier

    Enter the multiplier in the “multiply by” block and connect that block to the Adjustment block; only one adjustment can be used at a time.

  • Create the docker group

    Some Linux distributions automatically create the group when Docker Engine is installed with a package manager, so it may not need to be created manually.

  • Add the user to docker

    Use `usermod` to add the current user to the `docker` group.

  • Log in again to refresh groups

    Log out and back in so group membership is re-evaluated. In a Linux virtual machine, it may be necessary to restart the virtual machine; alternatively, run `newgrp docker` to activate the group changes.

  • Verify Docker without sudo

    Run `docker run hello-world`. The command downloads a test image and runs it in a container, which prints a message and exits when it runs.

  • Fix Docker config permissions

    If using `sudo` for Docker CLI commands earlier caused permission errors for `~/.docker/`, remove the directory, which is recreated automatically but loses custom settings, or change its ownership and permissions.

  • Verify user and Docker group

    Confirm that the user ID is unchanged, `docker` is the primary group, and test Docker access by running `hello-world`. Commands and applications started in this shell inherit access to the Docker socket.

  • Verify the original shell groups

    Run `id -nG` in the original shell and confirm that `docker` is no longer in its group list.

  • Enter the Host IP Address

    Enter the host computer’s IP address listed under “Starting server on *IP_address*:8000” when first starting `start.py`, or find it in another way.

  • Enable Robot Control

    After entering the IP address, return to the controller and toggle on `Control Robot`.

  • Refocus the Android App

    If Blossom is not initially controllable on Android, unfocus and refocus the app.

Data and training

  • Connect a USB webcam

    Connect a USB webcam to the computer.

  • Open the broadcaster page

    With the start.py script and ngrok tunnel running, open the broadcaster page on the desktop or laptop controlling the robot.

  • Select the webcam video source

    Select the connected webcam in the dropdown; a video feed should begin on the page.

  • Open the forwarding URL on mobile

    Open the ngrok forwarding URL in a mobile browser such as Safari.

  • Handle the self-signed certificate warning

    The browser may show a privacy warning; follow the document's linked guide to bypass it, as the development is local.

  • Confirm the video feed

    The mobile page should show the video feed from the webcam selected on the broadcaster page.

  • Hold the phone straight out

    Hold the phone straight out in front of you, as if taking a picture of something directly ahead.

  • Enable head-pose control

    Toggle the head switch to enable control and begin sending the phone's orientation to the robot.

  • Confirm motor commands are being sent

    The motor controller should begin blinking blue to show that it is sending motor commands.

Use it

  • Run the Nodding Sequence

    Enter `s`, press Enter, and then enter `yes` to make Blossom nod.

  • List Available Commands

    Enter `l` to list the available sequences.

  • Perform a Named Sequence

    Enter `s`, press Enter, and then enter the sequence name.

  • Loop a Gesture Sequence

    Separate two sequence names with `=`; for example, enter `s`, press Enter, and enter `yes=no` to play `yes` and then loop `no` indefinitely until another sequence is played.

  • Quit the Command-Line Interface

    Enter `q` to quit the CLI.

  • Access the Blossom GUI

    When starting the CLI without `-b`, access the GUI through `localhost:8000` or the displayed IP address followed by `:8000`; otherwise, the CLI prints the server URL.

  • Control robot orientation and height

    Move the phone to control the robot's pitch, yaw, and roll, and use the sliders to adjust its height.

  • Set the default robot orientation

    By default, the robot copies the phone's orientation identically, so the robot should face away from you.

  • Mirror the phone orientation

    Toggle `Mirror` to `On` so the robot faces you and looks toward the top of the phone.

  • Open the video editor

    Open a new terminal, run the Ubuntu or Mac command, and press Enter to open the video editor.

  • Load the video to watch

    Paste the video URL into the field and click `Update Video`.

  • Add the initial gesture block

    Use a Gesture block on the left side of the video editor and enter the starting time and gesture name.

  • Connect the gesture blocks

    Connect the blocks together to the initial block so that they trigger the gestures.

  • Create and reload gestures

    Create new gestures with the mobile app, then use them in the video editor with `Reload Gestures`.

  • Set movement looping

    Check `Loop` to repeat the movement indefinitely until the next gesture.

  • Connect to the Zero Access Point

    Connect the computer to the Zero’s access point.

  • Open the Zero Control Interface

    Access the control interface at 192.168.90.1:8080.

  • Access the Interface Locally

    Access https://{ip-address}:8080 using the same IP address used for SSH; https is required because http will not work.

  • Bypass the Self-Signed Warning

    Bypass the security warning because the certificates are self-signed.

  • Connect to the Zero Access Point

    Connect to the access point broadcast by the Zero. The SSID may resemble raspberrypi-someNumbersAndLetters, and the password is the one printed after running sudo wifi-ap-sta start.

  • Access the Interface via Access Point

    While connected to the access point, access the interface at https://192.168.90.1:8080 regardless of the Zero's local IP address.

  • Keep the shell for Docker work

    Use this shell only for Docker-related commands, or verify the group ownership of files you create. Files and directories created from it normally have `docker` as their group owner.

  • Control Orientation and Height

    Move the phone to control the robot’s pitch, yaw, and roll, and use the sliders for center height and the ears.

Common problems

  • Motor ID changes and calibration scripts fail #1 #39 #91 #93
  • Blossom Expo SDK and publishing tools fail during setup #4 #32
  • Missing Python dependency modules prevent installation #31
  • Sequences endpoint errors break web gesture control #2
  • Specified fasteners and wood are unavailable or dimensionally mismatched #6 #8 #9
  • Assembly documentation and 6mm template contain errors and missing parts #12 #92

Parts

  • Original: five Dynamixel XL‑320s (three tower motors pulling the head cables, one base yaw motor, one head accessory motor), a USB2AX or USB2Dynamixel controller, 5V supply
  • Original structure: laser-cut 12″×12″ 6 mm and 3 mm craft plywood, 1.5 mm acrylic pulleys, a 3D-printed centre bracket, a bearing, six #32 rubber bands, fishing line
  • Rebuild motors: four Dynamixel XL330‑M288s plus a U2D2 (about $132), or an Arduino with four micro servos (about $25)
  • Rebuild structure: A–F and M runners (printed or laser-cut), an optional 12-wire slip ring for rotation past 360° (about $22), six 4 mm rubber bands, M2 screws
  • 2026 controller option: Raspberry Pi Zero 2 W plus a Raspberry Pi Pico (C++ PWM servo firmware)
  • Cover: a knitted or crocheted shell you make yourself (the wiki gives sample dimensions)

Tools

  • Original: a 12″×12″ laser cutter and a small 3D printer, screwdrivers, pliers, wood glue and superglue; the extended servo cable needs soldering and heat-shrink
  • Rebuild: an entry-level 3D printer (the creator uses a Creality Ender 3 with the supplied Cura profile), wire cutters, a 5V 3A (15 W) or larger USB supply

Skills

  • Python and the command line (Linux/macOS), setting servo IDs and calibrating
  • Knitting or crocheting the cover and making accessories
  • Optional for the rebuild: Raspberry Pi imaging, Docker and ROS 2

Software

  • hrc2/blossom-public: Python CLI and web UI, a React Native phone app, a Blockly video choreography editor
  • msgtn/r0b0: Flask‑SocketIO messaging middleware with phone-motion control in a mobile web page, WebRTC video, motion record and playback, and chat through the llm library; ROS 2 nodes and a Docker boot service added in 2026
  • msgtn/micropython-servo: Raspberry Pi Pico servo firmware (MIT)

Documents