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.

About 45 minutesLinux, macOS or WindowsBefore board bring-up

How the pieces connect

There are three links to get working, in this order:

Link 1

PC ↔ repository

Build and test the control core on your PC. No hardware is needed.

Link 2

PC ↔ Duo S (alone)

USB-C networking and SSH, with the Duo S powered from your PC.

Link 3

PC ↔ Duo S on the board

Ethernet or the J22 serial console, with the board powering the Duo S.

Never power the Duo S from two sources at once

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

ItemWhy
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 upThe robot's computer. The board was drawn against the V1.2 Duo S.
microSD card, 8 GB or larger, and a card readerThe boot image.
USB-C data cablePower 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 leadThe 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 VFor 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.

Note

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

  1. 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.
  2. Flash the microSD cardUse balenaEtcher or Raspberry Pi Imager (“Use custom”), or dd on 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
  3. 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 B is ARM, one that starts with C is RISC-V.
  4. 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
PCWhat to expect
LinuxDriver-free. A new interface (usb0 or enx…) appears with a 192.168.42.x address.
macOSDriver-free. The adapter appears in System Settings → Network.
Windows 11 / recent 10Usually 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/.

Checkpoint

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

1GND2Duo TX3Duo RX

Adapter wiring

Cross TX and RX. Leave the adapter's power pin unconnected.

GND → 1RX ← 2TX → 3

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

  1. 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.
  2. Start the console firstOpen the serial terminal before switching on, so you see the whole boot log.
  3. 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.
  4. Log inAs root with your new password, either on the console or by SSH over Ethernet.
The real-time buses belong to the C906

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

SymptomCheck
No network adapter appears over USBUse 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 existsWait 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 bootsThe 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 consoleThe 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 consoleCheck 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 boardThe supply is in current limit, or VSYS dips. VSYS should sit near 4.9–5.0 V. See stage 4.

Next steps