01. 入门指南

ESPClaw 是什么

ESPClaw 是一个基于 ESP32-S3 微控制器的智能机械爪项目。它使用 SG90 微型舵机驱动机械爪的开合，通过 WiFi 提供网页控制界面，让你用手机或电脑就能远程操控机械爪。

整个项目从硬件到固件完全开源，适合作为嵌入式物联网和机器人入门的综合练习。你不需要深厚的机械或嵌入式背景，只要有一些 C 语言基础和动手能力，就能把它做出来。

功能特性

• 基于 ESP-IDF 框架，使用 C 语言开发
• ESP32-S3 双核处理器，240MHz 主频
• SG90 舵机驱动机械爪开合
• WiFi 接入点模式（AP Mode），无需路由器
• HTTP + WebSocket 网页实时控制
• 平滑角度过渡算法，动作流畅
• 支持 OTA 远程固件升级
• 可扩展手势控制、ROS2 集成

硬件清单

在开始之前，你需要准备以下硬件：

开发环境搭建

ESPClaw 使用乐鑫官方的 ESP-IDF 框架开发。有两种推荐的环境搭建方式。

方式一：Linux 原生安装

如果你用的是 Ubuntu 或 Debian，原生安装最直接。

# 安装编译工具链依赖
sudo apt-get update
sudo apt-get install git wget flex bison gperf python3 python3-pip \
  python3-venv cmake ninja-build ccache libffi-dev libssl-dev dfu-util \
  libusb-1.0-0

# 克隆 ESP-IDF（推荐 v5.1 或更高）
mkdir -p ~/esp
cd ~/esp
git clone -b v5.3 --recursive https://github.com/espressif/esp-idf.git

# 安装工具链
cd ~/esp/esp-idf
./install.sh esp32s3

# 设置环境变量（每次打开新终端需要执行）
source ~/esp/esp-idf/export.sh

为了方便，可以把环境变量设置加到 ~/.bashrc：

echo "alias get_idf='source ~/esp/esp-idf/export.sh'" >> ~/.bashrc

方式二：Docker 方式

如果你不想污染本机环境，或者需要在 Windows/macOS 上开发，使用 Docker 更干净。

# 拉取 ESP-IDF Docker 镜像
docker pull espressif/idf:v5.3

# 在项目目录中运行容器
cd /path/to/espclaw
docker run --rm -v $PWD:/project -w /project \
  -e HOME=/tmp -u $UID \
  -it espressif/idf:v5.3

Hello World：点亮板载 LED

搭建好环境后，我们来写第一个程序。创建一个新工程：

# 复制 ESP-IDF 的 hello_world 示例
cp -r $IDF_PATH/examples/get-started/hello_world ~/esp/espclaw-hello
cd ~/esp/espclaw-hello

选择目标芯片为 ESP32-S3：

idf.py set-target esp32s3

编译：

idf.py build

连接开发板到电脑，查看串口设备：

ls /dev/ttyUSB*  # 通常是 /dev/ttyUSB0

烧录并监视输出：

idf.py -p /dev/ttyUSB0 flash monitor

如果一切正常，你会看到 “Hello world!” 打印输出，随后是芯片信息和 FreeRTOS 任务调度日志。按 Ctrl+] 退出监视器。

常见问题

Q：烧录时报 “Failed to connect” 错误 A：检查 USB 线是否支持数据传输（有些充电线不能传数据），按住开发板 BOOT 键再试。

Q：Docker 下无法访问串口 A：运行容器时加上 --device=/dev/ttyUSB0 和 -v /dev:/dev 参数。

Q：编译速度很慢 A：首次编译需要下载工具链，后续会快很多。也可以加上 -j4 参数并行编译：idf.py build -j4。

下一步

环境准备好之后，进入硬件组装与接线，开始动手搭建机械爪。