# omnix_robotics

**Repository Path**: chenjmg/omnix_robotics

## Basic Information

- **Project Name**: omnix_robotics
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-22
- **Last Updated**: 2026-07-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

```text
 ______     __    __     __   __     __     __  __    
/\  __ \   /\ "-./  \   /\ "-.\ \   /\ \   /\_\_\_\   
\ \ \/\ \  \ \ \-./\ \  \ \ \-.  \  \ \ \  \/_/\_\/_  
 \ \_____\  \ \_\ \ \_\  \ \_\\"\_\  \ \_\   /\_\/\_\ 
  \/_____/   \/_/  \/_/   \/_/ \/_/   \/_/   \/_/\/_/ 
```

# OmniX Robotics

**OmniX Robotics** 是面向导航、运动控制、SLAM 与边缘 AI 的自主机器人开发平台。

中文定位：**OmniX Robotics 全域自主机器人平台**。

## 项目范围

- **导航（Navigation）**：全局规划、局部规划、路径跟随、行为协调。
- **运动控制（Motion Control）**：底盘抽象、速度控制、轨迹跟踪、安全限制。
- **SLAM**：建图、定位、位姿图接口、地图管理。
- **AI**：感知、检测、分割、模型运行时集成、边缘推理。
- **机器人中间件（Robot Middleware）**：ROS2 / TogetheROS.Bot 适配层，以及纯 C++ 核心接口。
- **硬件支持（Hardware Support）**：传感器驱动、底盘驱动、RDK X3 适配层。

## 初始架构

```text
omni_robotics/
├── apps/                 # 可运行应用
├── 3rdparty/             # 第三方开源库源码/单头库
├── modules/
│   ├── core/             # 纯 C++ 核心工具与接口
│   ├── common/           # 通用基础设施与公共工具
│   ├── motion/           # 运动控制
│   ├── navigation/       # 规划与导航
│   ├── slam/             # 建图与定位
│   ├── ai/               # AI 感知与推理
│   ├── drivers/          # 机器人硬件驱动
│   ├── proto/            # Google Protobuf 协议与消息定义
│   └── ros_bridge/       # ROS2 / TogetheROS.Bot 集成
├── configs/              # 运行时配置
├── docs/                 # 设计文档与计划
├── scripts/              # 辅助脚本
└── tests/                # 单元测试 / 集成测试
```

## 通信

内部通信协议统一放在 `modules/proto` 中：

- 协议定义：Google Protobuf（`*.proto`）。
- 传输方式：ZMQ 发送具体 Protobuf 消息的 `SerializeAsString()` 载荷。
- 本机进程间通信默认使用 ZMQ `ipc://`，业务模块按 topic 发布/订阅。
- 首批构建目标：`omnix_proto` 与 `omnix_proto_node`。

## 构建

项目提供 `build.py` 作为统一构建入口。脚本默认使用 OmniX OpenExplorer 派生镜像 `omnix_robotics/openexplorer_x3_toolchain:v1.0.0` 配置、编译并安装产物。该镜像基于官方 RDK X3 / OpenExplorer 镜像构建，并将项目缺失的 `glog`、`gflags`、`protobuf`、`libzmq`、`cppzmq` 等依赖预先编译到 `/opt/omnix/deps/`。

### 1. 构建 OmniX OpenExplorer 派生镜像

首次构建项目前，先构建派生工具链镜像：

```bash
python3 build.py --build-image
```

等价的 Docker 命令为：

```bash
docker build \
  -f docker/openexplorer/Dockerfile \
  --build-arg BASE_IMAGE=openexplorer/ai_toolchain_ubuntu_20_x3j5_gpu:v1.0.0 \
  -t omnix_robotics/openexplorer_x3_toolchain:v1.0.0 \
  .
```

如果需要临时回退官方镜像，可使用：

```bash
python3 build.py --image openexplorer/ai_toolchain_ubuntu_20_x3j5_gpu:v1.0.0
```

如果本机已经存在旧的 `omnix_x3_toolchain` 容器，且该容器不是由当前镜像创建，脚本会停止并提示删除旧容器或换容器名：

```bash
docker rm -f omnix_x3_toolchain
# 或
python3 build.py --container-name omnix_x3_toolchain_new
```

### 2. 选择默认编译环境

首次构建建议先选择并保存默认环境：

```bash
python3 build.py --env
```

菜单中可选择：

- `x86`：本地仿真 / PC 调试环境，产物安装到 `release/x86/`。
- `arm`：RDK X3 板端交叉编译环境，产物安装到 `release/arm/`。

选择结果会写入 `.omnix_build_env`。之后直接执行 `python3 build.py` 时，会优先使用该默认环境；如果还没有设置默认环境，则默认使用 `arm`。

### 3. 常用构建命令

```bash
# 使用已保存的默认环境构建全部可安装目标
python3 build.py

# 显式指定 x86 环境构建
python3 build.py --platform x86

# 显式指定 arm 环境交叉编译
python3 build.py --platform arm

# 只构建并安装指定目标
python3 build.py --target omnix_demo

# arm 环境下清理后重新构建指定目标
python3 build.py --platform arm --clean --target omnix_demo
```

### 4. 构建流程

`build.py` 会自动完成以下步骤：

1. 检查 Docker 服务是否运行，未运行时尝试启动。
2. 检查默认镜像 `omnix_robotics/openexplorer_x3_toolchain:v1.0.0` 是否存在，不存在时尝试拉取；首次使用建议先执行 `python3 build.py --build-image` 在本机构建。
3. 创建或复用持久化容器 `omnix_x3_toolchain`，并校验容器镜像是否匹配当前 `--image`。
4. 在容器内执行 CMake 配置与编译。
5. 将构建产物安装到 `release/<env>/`。
6. 构建结束后打印平台、目标、产物路径与 MD5。

### 5. 常用选项

- `--platform x86|arm`：临时指定本次构建平台，会覆盖 `.omnix_build_env` 中的默认环境。
- `--target <name>` / `-t <name>`：只构建指定 CMake 目标，例如 `omnix_demo`。
- `--clean`：构建前删除所选平台的构建目录。
- `--build-type Debug|Release|RelWithDebInfo|MinSizeRel`：指定 CMake 构建类型，默认 `Release`。
- `--dry-run`：只打印 Docker / CMake 命令，不实际执行构建。
- `--extra-cmake-arg <arg>`：向 CMake 配置阶段追加参数，可重复使用。
- `--build-image`：构建 OmniX OpenExplorer 派生镜像后退出。
- `--base-image <image>`：构建派生镜像时覆盖基础 OpenExplorer 镜像。
- `--dockerfile <path>`：构建派生镜像时覆盖 Dockerfile 路径。
- `--image <image>`：覆盖默认 Docker 镜像。
- `--container-name <name>`：覆盖默认持久化构建容器名称。

### 6. 产物使用约定

构建完成后，产物会按环境安装到：

```text
release/x86/    # x86 本地 / 仿真产物
release/arm/    # RDK X3 板端 ARM 产物
```

给板子推送程序时，优先使用 `release/arm/<target>`，不要直接从 `build/` 目录取，避免 x86 / arm 二进制混淆。

`release/` 是本地构建产物目录，不需要提交到仓库。

### 7. 本地 CMake 冒烟构建

如果本地 PC 已安装所需原生依赖，也可以不经过 Docker，直接使用 CMake 做冒烟构建：

```bash
cmake -S . -B build
cmake --build build -j2
ctest --test-dir build --output-on-failure
./build/apps/omnix_demo/omnix_demo
```

## RDK X3 资源

- D-Robotics 官方文档中心：https://developer.d-robotics.cc/rdk_doc_center/
- RDK X3 镜像 / 系统烧录指南：https://developer.d-robotics.cc/rdk_doc/Quick_start/install_os/rdk_x3/system_burn

## 命名

- 品牌 / 项目名：**OmniX Robotics**
- 仓库 / 目录名：`omnix_robotics`
- 核心命名空间：`omnix`

## 当前阶段

项目目前处于初始工程骨架阶段。首个实现里程碑是在绑定 ROS2 / TogetheROS.Bot 或 RDK X3 厂商 SDK 前，先定义稳定的 C++ 模块边界。