diff --git a/README.md b/README.md
new file mode 100644
index 0000000..48efd5e
--- /dev/null
+++ b/README.md
@@ -0,0 +1,129 @@
+# CRAIC — Camera-Robot AI Control System
+
+ESP32-S3 双核摄像头 + ROS 2 键盘遥控 + UDP 实时通讯的一体化机器人控制系统。
+
+## 项目结构
+
+```
+craic/
+├── jxbeye/                    # ESP32-S3 摄像头固件 (PlatformIO)
+│   ├── src/main.cpp           # 双核并行推流 + AsyncUDP + ESP-NOW
+│   ├── platformio.ini         # 构建配置 (ESP32-S3-WROOM-1-N16R8)
+│   ├── boards/                # 自定义板级定义
+│   ├── lib/FTServo/           # 飞特舵机控制库
+│   └── include/ / test/
+├── ros2/                      # ROS 2 Humble 键盘遥控
+│   └── src/udp_teleop/        # 底盘 + 6轴机械臂 UDP 遥控节点
+├── tools/                     # 调试工具
+│   └── udp_server.py          # UDP 回显测试服务器
+└── .gitignore
+```
+
+## 硬件
+
+| 组件 | 型号 |
+|------|------|
+| 主控 | ESP32-S3-WROOM-1-N16R8 (16MB Flash, 8MB PSRAM Octal) |
+| 摄像头 | OV2640 (XGA 1024×768, JPEG) |
+| 舵机 | 飞特 SCS/STS 系列串行舵机 |
+
+## 功能
+
+### 1. ESP32-S3 固件 (`jxbeye/`)
+
+- **双核并行架构**：Core 0 负责摄像头采集，Core 1 负责 WiFi 推流
+- **MJPEG 实时推流**：Web 浏览器直接访问 `http://<IP>` 查看实时画面
+- **AsyncUDP 非阻塞通讯**：UDP 指令由中断回调处理，不干扰推流
+- **ESP-NOW**：低延迟点对点通信
+- **在线 WiFi 配置**：通过 Web 页面或串口修改 SSID/密码，自动保存到 NVS
+
+### 2. ROS 2 键盘遥控 (`ros2/src/udp_teleop/`)
+
+- **底盘遥控**：W/S 前进后退、A/D 左右平移、Q/E 旋转（差速驱动）
+- **机械臂遥控**：6 轴关节角度独立控制，高度升降
+- **多平台键盘后端**：
+  - `stdin` — Linux/macOS 终端原生输入，零依赖
+  - `pynput` — 跨平台按键监听
+  - `win_poll` — Windows Win32 API 轮询
+- **可配置参数**：速度、步长、目标 IP/端口均通过 YAML 配置
+
+### 3. UDP 通讯协议
+
+所有指令通过 UDP 端口 `8888` 发送，格式：
+
+```
+# 底盘控制
+XYW:<X速度>:<Y速度>:<W角速度>:XZHY\n
+
+# 机械臂控制
+JXB:<高度>:<J2>:<J3>:<J4>:<J5>:<J6>:0:0:EZHY\n
+
+# 激光控制
+LASERON / LASEROFF
+
+# 串口透传
+<any payload ending with ZHY or \n>
+```
+
+## 快速开始
+
+### 编译 & 烧录 ESP32 固件
+
+```bash
+cd jxbeye
+pio run -t upload
+pio device monitor
+```
+
+首次启动后 ESP32 创建热点 `ESP32-S3-Camera`（密码 `12345678`），浏览器访问 `http://192.168.4.1`。
+
+### 运行 ROS 2 键盘遥控
+
+```bash
+# 创建环境（首次）
+conda create -n ros2_humble -c robostack-staging -c conda-forge ros-humble-desktop
+conda install -n ros2_humble -c robostack-staging -c conda-forge colcon-common-extensions
+conda run -n ros2_humble pip install pynput
+
+# 构建 & 运行
+conda activate ros2_humble
+cd ros2
+colcon build --symlink-install --packages-select udp_teleop
+source install/setup.bash
+
+# 启动键盘遥控（默认目标 192.168.233.67:8888）
+ros2 run udp_teleop keyboard_control \
+    --ros-args --params-file src/udp_teleop/config/params.yaml
+```
+
+### 测试 UDP 通讯
+
+```bash
+# 启动回显服务器
+python tools/udp_server.py
+
+# 发送测试指令
+echo 'XYW:100:0:0:XZHY' | nc -u 127.0.0.1 8888
+```
+
+### 串口配置 WiFi
+
+在 ESP32 串口监视器中发送：
+
+```
+WIFI:热点名称:密码
+```
+
+设备自动保存配置并重启。
+
+## 依赖
+
+| 环境 | 依赖 |
+|------|------|
+| ESP32 | PlatformIO, Arduino framework, esp32-camera |
+| ROS 2 | ROS 2 Humble (Conda robostack), pynput |
+| 测试 | Python 3, Unix netcat |
+
+## 许可
+
+待定。