> For the complete documentation index, see [llms.txt](https://anonymous-humanoid.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://anonymous-humanoid.gitbook.io/docs/getting-started-software/embedded-environment-setup.md).

# Embedded Environment Setup

## System Tested

* Ubuntu 22.04

## Software Architecture Overview

The attached figure provides an overview of the software architecture.

Four major software dependencies are required: **Java, ROS 2, Anaconda, and LCM**. The main `humanoid-control` codebase runs on **ROS 2**, which serves as the primary framework for the robot drivers and control applications.

<figure><img src="https://3830802523-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHes4aC9tJcLREA5OZOli%2Fuploads%2F2sP7Wxx3VAvn5Xx6gL5O%2Farc_bridge_ros_architecture.drawio%20(1).svg?alt=media&amp;token=35fbe306-5ef8-41cf-a457-23435198300c" alt=""><figcaption></figcaption></figure>

## Setting Up Dependencies

**Anaconda, Java, and LCM** are primarily required by `arc-bridge`, which provides the interface to the external simulation backend. In addition to simulation, some legacy control nodes also communicate through `arc-bridge` and LCM, mainly to receive gamepad input.

Therefore, although most of the project runs directly within ROS 2, the `arc-bridge` dependencies are still required to support the simulation environment and compatibility with these legacy nodes.

{% stepper %}
{% step %}

### Java

Install OpenJDK 17:

```bash
sudo apt install openjdk-17-jdk
```

{% endstep %}

{% step %}

### ROS 2

Install ROS 2 by following the instructions \[[link](https://docs.ros.org/en/humble/Installation/Ubuntu-Install-Debs.html)].

After installation, install the required Pinocchio and ProxSuite packages:

```bash
sudo apt install ros-humble-pinocchio ros-humble-proxsuite
```

{% endstep %}

{% step %}

### Anaconda / Miniconda

Install Anaconda or Miniconda by following the instructions \[[link](https://www.anaconda.com/docs/getting-started/anaconda/install/linux-install)].

During installation, allow the installer to update your shell profile so that `conda` is available in newly opened terminals.

<figure><img src="https://3830802523-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHes4aC9tJcLREA5OZOli%2Fuploads%2FPMpZ3izdOtnj6O2G45sr%2Fp0.png?alt=media&amp;token=c7fa6441-39cb-4b15-83de-8d3de216472a" alt=""><figcaption></figcaption></figure>

After installation, open a new terminal and accept the Anaconda Terms of Service:

<figure><img src="https://3830802523-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHes4aC9tJcLREA5OZOli%2Fuploads%2F552XYT94GkJoMddEtWfR%2Fp1.png?alt=media&amp;token=58a81273-82d0-4eef-a848-fa0354bb6075" alt=""><figcaption></figcaption></figure>

{% code overflow="wrap" %}

```bash
conda tos accept --override-channels --channel https://repo.anaconda.com/pkgs/main conda tos accept --override-channels --channel https://repo.anaconda.com/pkgs/r
```

{% endcode %}

Then disable automatic activation of the Conda `base` environment:

```bash
conda config --set auto_activate_base false
```

This prevents Conda from modifying the default shell environment each time a new terminal is opened.
{% endstep %}

{% step %}

### LCM

We need to build [LCM](https://github.com/lcm-proj/lcm) from source. The APT-managed LCM package does not provide the required CMake configuration files, so LCM should be built and installed from source:

```bash
mkdir -p ~/projects
cd ~/projects

git clone git@github.com:lcm-proj/lcm.git
cd lcm

mkdir build
cd build

cmake ..
make -j$(nproc)
sudo make install
```

The `-j$(nproc)` option allows `make` to use all available CPU cores to accelerate compilation.
{% endstep %}

{% step %}

### libusb

The `dm_motor` module requires `libusb` for USB2CANFD communication. Ubuntu 22.04 may already include the runtime library, but the development package should be installed with:

```bash
sudo apt install libusb-1.0-0-dev
```

{% endstep %}
{% endstepper %}

## Compile the `humanoid-control` packages

{% stepper %}
{% step %}

### Clone and setup the repository

Clone the `humanoid`repository together with all submodules:

```bash
cd ~/projects # Get back to projects folder from LCM build folder.
git clone --recurse-submodules git@github.com:/humanoid-control.git
cd humanoid-control
```

If the repository was cloned without the `--recurse-submodules` option, initialize and download the submodules from the project root directory:

```bash
git submodule update --init --recursive
```

{% endstep %}

{% step %}

### Configure the `arc-bridge` Submodule

By default, Git submodules are checked out in a detached `HEAD` state. Switch the `arc-bridge` submodule to its `main` branch:

```bash
cd external/arc-bridge
git switch main
```

For older versions of Git, use:

```bash
git checkout main
```

Return to the project root directory and update `arc-bridge` from its remote `main` branch:

```bash
cd ../..
git submodule update --remote external/arc-bridge
```

{% endstep %}

{% step %}

### Set Up `arc-bridge`

Follow the `arc-bridge` README for the detailed installation procedure.

Enter the `arc-bridge` directory:

```bash
cd external/arc-bridge
```

Create the Conda environment:

```bash
conda env create -f environment_py310.yml
```

For Python 3.9, use:

```bash
conda env create -f environment.yml
```

During environment creation, the installation may report an error related to `casadi 3.7`. This does not prevent the following setup steps from being completed.

Activate the `arcpy` environment:

```bash
conda activate arcpy
```

Generate the LCM message types:

```bash
bash gen_lcm_types.sh
```

Install `arc-bridge` as an editable Python package in compatibility mode:

```bash
pip install -e . --no-deps --config-settings editable_mode=compat
```

{% endstep %}

{% step %}

### Setup `ONNX Runtime`

The whole-body controller uses the **CPU version of ONNX Runtime** for policy inference.

Download the appropriate ONNX Runtime release for your platform and CPU architecture from this \[link].

After downloading the compressed package, extract it and move the extracted ONNX Runtime directory to `/opt/onnxruntime`, which is the default location referenced by the project's `CMakeLists.txt`.

<mark style="color:$warning;">**Replace**</mark><mark style="color:$warning;">**&#x20;**</mark><mark style="color:$warning;">**`[your onnx runtime compressed file]`**</mark><mark style="color:$warning;">**&#x20;**</mark><mark style="color:$warning;">**and**</mark><mark style="color:$warning;">**&#x20;**</mark><mark style="color:$warning;">**`[your unzipped onnx runtime folder name]`**</mark><mark style="color:$warning;">**&#x20;**</mark><mark style="color:$warning;">**with the actual file and directory names for your downloaded ONNX Runtime version.**</mark>

```bash
tar -xzf [your onnx runtime compressed file]
sudo mv [your unzipped onnx runtime folder name] /opt/onnxruntime
```

Add the ONNX Runtime library directory to the system library search path:

```bash
echo "/opt/onnxruntime/lib" | sudo tee /etc/ld.so.conf.d/onnxruntime.conf
sudo ldconfig
```

{% endstep %}

{% step %}

### Build the ROS 2 Workspace

After completing the `arc-bridge` setup, return to the `humanoid-control` project root:

```bash
cd ../..
```

Deactivate the Conda environment before building the ROS 2 workspace:

```bash
conda deactivate
```

Make sure no Conda environment is active before running `colcon build`.

Some ROS 2 nodes, such as `dm_motor_demo`, depend on the generated LCM message types during compilation. Therefore, the `arc-bridge` environment setup and LCM type generation must be completed before building the workspace.

Compile the project with:

```bash
colcon build \
    --cmake-args -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -Wno-dev \
    --symlink-install
```

After the build completes, source the workspace:

```bash
source install/setup.bash
```

{% endstep %}
{% endstepper %}

## DAMIAO Motor Setup

Currently, the software repository uses an older version of the DAMIAO Motor SDK that is incompatible with the latest firmware shipped with DAMIAO USB2CANFD modules. To ensure proper communication with the existing software stack, the USB2CANFD module firmware must be downgraded to version 1003.

{% embed url="<https://gitee.com/kit-miao/usb2canfd/blob/master/%E5%9B%BA%E4%BB%B6/%E5%87%BA%E5%8E%82%E5%9B%BA%E4%BB%B6/%E5%8E%86%E5%8F%B2%E5%9B%BA%E4%BB%B6/dm_usb2fdcan_app_1003.enc>" %}

To downgrade the firmware, you will need the DMTools:

{% embed url="<https://gitee.com/kit-miao/motor-debugging-tool/tree/master>" %}

After installation, plug in the USB2CANFD tool and follow the instruction below to downgrade the firmware.

<figure><img src="https://3830802523-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHes4aC9tJcLREA5OZOli%2Fuploads%2F93F8imBygn9MPHVaYqUX%2Fimage.png?alt=media&amp;token=98ac8a90-1289-47a7-bceb-bd4226dc5596" alt=""><figcaption></figcaption></figure>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://anonymous-humanoid.gitbook.io/docs/getting-started-software/embedded-environment-setup.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.