Start here
First steps: connect to your PC
Set up the development computer, give the Milk-V Duo S a working image, and open a shell on it. First on its own over USB, then mounted on the Robotics Board.
How the pieces connect
There are three links to get working, in this order:
PC ↔ repository
Build and test the control core on your PC. No hardware is needed.
PC ↔ Duo S (alone)
USB-C networking and SSH, with the Duo S powered from your PC.
PC ↔ Duo S on the board
Ethernet or the J22 serial console, with the board powering the Duo S.
Once the Duo S is on the Robotics Board, the board feeds its VSYS pins. Do not also plug a powered USB-C cable into the Duo S: whether Duo S VSYS and USB VBUS are tied together has not been confirmed, and the two supplies could back-feed each other. Use Ethernet or the serial console instead, as in step 4.
What you need
| Item | Why |
|---|---|
| A PC (Ubuntu 24.04 recommended; macOS and Windows work for SSH) | Building, flashing, logging in. ROS 2 tools are easiest on Ubuntu. |
| Milk-V Duo S (SG2000), headers pointing up | The robot's computer. The board was drawn against the V1.2 Duo S. |
| microSD card, 8 GB or larger, and a card reader | The boot image. |
| USB-C data cable | Power and networking for the Duo S on its own. Charge-only cables will not work. |
| 3.3 V USB-to-UART adapter (CP2102, CH340, FT232…) and a JST-SH 3-pin lead | The Linux console on the board's J22. It must be 3.3 V logic, not 5 V. |
| Ethernet cable and a router with DHCP (optional) | Network access once the Duo S is on the board. |
| Current-limited bench supply, 12–16.8 V | For powering the board in step 4. Never a LiPo for first power-on. |
1. Set up the development computer
The control core is plain C11 and builds and tests on your PC with no robot attached. Start here: if these tests fail, nothing on the hardware will be meaningful.
# Ubuntu 24.04: compilers, CMake, Python and the RISC-V cross toolchain
$ sudo apt install build-essential cmake git python3-pip \
gcc-riscv64-unknown-elf picolibc-riscv64-unknown-elf
# Get the repository (use your clone URL), then the pinned host tools
$ git clone <repository-url> balance-robot && cd balance-robot
$ python3 -m pip install -r tools/requirements.txt
Then run the same checks the CI runs:
$ make test # host build, unit tests and the closed-loop plant simulation
$ make asan # the same with address and undefined-behaviour sanitizers
$ make cross # core + SG2000 port for the C906 core (RV64GC)
make test runs two programs. balance_tests holds the unit tests. balance_closed_loop drives the real runtime, the 10 kHz drive loop and FOC against a simulated wheel-pendulum built from the robot's CAD mass properties. It must recover from a lean at 14.8 V and 12.2 V and drive at a commanded speed.
Passing host tests shows that signs, units, frames and limits are consistent end to end. It does not prove that the physical robot is stable: that needs measured motors and mass properties.
2. Prepare the Duo S
- Download the official imageUse Milk-V's Buildroot SDK V2 images, which support the Duo S's ARM core: duo-buildroot-sdk-v2 releases. Pick the Duo S, ARM64, SD card image. Use firmware V1.1.2 or later: older images use RNDIS instead of CDC-NCM for USB networking.
- Flash the microSD cardUse balenaEtcher or Raspberry Pi Imager (“Use custom”), or
ddon Linux:$ lsblk # find the card, e.g. /dev/sdX; check it twice $ unzip milkv-duos-*-arm64-*.img.zip $ sudo dd if=milkv-duos-*.img of=/dev/sdX bs=4M conv=fsync status=progress - Select the ARM coreThe Duo S has a switch that chooses whether the big core boots as RISC-V or ARM. This project runs Linux on the ARM Cortex-A53; the C906 little core is reserved for real-time control. Set the switch to ARM before powering up. You can confirm it on the console: a boot log that starts with
Bis ARM, one that starts withCis RISC-V. - Insert the cardPut the microSD card in the Duo S. Leave the Duo S off the Robotics Board for now.
3. First login over USB-C
With the Duo S on its own (not on the board), connect its USB-C port to your PC with a data cable. This powers the board and creates a USB network adapter (CDC-NCM). Once it has booted, the Duo S hands your PC an address by DHCP.
$ ping 192.168.42.1
$ ssh root@192.168.42.1 # default password: milkv
| PC | What to expect |
|---|---|
| Linux | Driver-free. A new interface (usb0 or enx…) appears with a 192.168.42.x address. |
| macOS | Driver-free. The adapter appears in System Settings → Network. |
| Windows 11 / recent 10 | Usually driver-free. On older systems, open Device Manager, update the unknown device's driver and choose Network adapters → Microsoft → UsbNcm Host Device. |
Once you are in, change the default password and take a look around:
[root@milkv-duo]~# passwd
[root@milkv-duo]~# uname -a # should report aarch64
[root@milkv-duo]~# cat /proc/cpuinfo | head
[root@milkv-duo]~# ip addr
To copy files across, use scp from your PC, for example scp build/tool root@192.168.42.1:/root/.
You can SSH into the Duo S and uname -m prints aarch64. Power it down (poweroff, then unplug) before going on.
4. Connect to the Duo S on the Robotics Board
Do this only after the board has passed bring-up stages 1–3 without the Duo S. Fit the Duo S on its four M2.5 standoffs with the board's J8/J9 sockets on its headers, then choose how to talk to it:
Option A: Ethernet
The Duo S's RJ45 port sits in the board's notch and stays reachable. Plug it into a router with DHCP, power the board (below), and find the address on your router's client list, or read it from the console with ip addr show eth0. Then ssh root@<address>.
Option B: serial console on J22
J22 is a 3-pin JST-SH connector that carries the Duo S's UART0, the Linux console. It supplies no power.
J22 · Debug UART0
JST-SH 1.0 mm, 3 pins, 3.3 V logic
Adapter wiring
Cross TX and RX. Leave the adapter's power pin unconnected.
Settings: 115200 baud, 8 data bits, no parity, 1 stop bit, no flow control.
# Linux (the adapter is usually /dev/ttyUSB0 or /dev/ttyACM0)
$ sudo usermod -aG dialout $USER # once, then log out and in
$ picocom -b 115200 /dev/ttyUSB0 # quit with Ctrl-A Ctrl-X
# macOS
$ screen /dev/tty.usbserial-* 115200
# Windows: PuTTY, Connection type "Serial", COMx, speed 115200
Power up through the board
- Set the bench supply12.0 V with a 1 A current limit, connected to J1 (XT30: pin 2 is
+, pin 1 is−; check your lead with a meter). No motors, servos or battery yet. - Start the console firstOpen the serial terminal before switching on, so you see the whole boot log.
- Switch onThe green power LED lights. The yellow EN and red FLT LEDs stay dark: the motors are disabled until firmware explicitly arms them. Linux boots and the console offers a login prompt.
- Log inAs
rootwith your new password, either on the console or by SSH over Ethernet.
In the finished system Linux must not claim I²C4, SPI3, PWM controllers 0–2 or the board's GPIOs; the C906 firmware owns them. For bring-up only, you can enable I²C4 and SPI3 in a test device tree and use i2c-tools and spidev. Remove it before running the C906 firmware.
With a test device tree loaded, a scan of the board's I²C bus should show exactly two devices (bus numbers depend on the image):
[root@milkv-duo]~# i2cdetect -l # find the I2C4 bus number
[root@milkv-duo]~# i2cdetect -y <bus>
# 0x48 ADS1115 rail monitor
# 0x68 BMI323 IMU (chip ID 0x43)
The full sensor checks, with expected register values and rail readings, are in bring-up stage 4.
5. See the robot on your PC
The robot's description package is generated from the CAD and runs on your PC today. Install ROS 2 Jazzy (Ubuntu 24.04), then:
$ cd ros2
$ colcon build --packages-select balance_robot_description
$ source install/setup.bash
$ ros2 launch balance_robot_description display.launch.py # RViz with joint sliders
$ ros2 launch balance_robot_description mock.launch.py # ros2_control with mock hardware
You drive two hip joints (r_hip_joint, l_hip_joint, 15–55°) and two wheel joints. The knees and four-bar links follow the hips as mimic joints. Keep RViz, simulation and heavy navigation on the PC: the Duo S has 512 MB of RAM.
Troubleshooting
| Symptom | Check |
|---|---|
| No network adapter appears over USB | Use a data cable, not a charge-only one. Use firmware V1.1.2 or later (CDC-NCM). On older Windows, install the UsbNcm driver. |
ping 192.168.42.1 fails, but the adapter exists | Wait about 30 s after power-up for DHCP. Check that the PC's adapter has a 192.168.42.x address. |
Boot log starts with C, or nothing boots | The core switch is on RISC-V or doesn't match the image. Set it to ARM and use the ARM64 image. |
| Garbage on the serial console | The baud rate is not 115200, TX and RX are not crossed, or the adapter is set to 5 V. |
| Nothing at all on the serial console | Check GND on J22 pin 1 and that TX and RX are crossed. Check that the board's 5 V rail (TP8) reads about 5.3 V. |
| Duo S resets while booting on the board | The supply is in current limit, or VSYS dips. VSYS should sit near 4.9–5.0 V. See stage 4. |